.TH nfcapd 1 2009\-09\-09 "" ""
.SH NAME
nfcapd \- netflow capture daemon
.SH SYNOPSIS
.HP 5
.B nfcapd [options]
.SH DESCRIPTION
.B nfcapd
is the netflow capture daemon of the nfdump tools. It reads netflow
data from the network and stores it into files. The output file
is automatically rotated and renamed every n minutes \- typically
5 min \- according the timestamp YYYYMMddhhmm of the interval e.g. 
nfcapd.201907110845 contains the data from July 11th 2019 08:45 onward.
If the time interval is smaller then 60s, the naming extends to seconds
e.g. nfcapd.20190711084510. 

.P
Netflow version v1, v5, v7 and v9 and IPFIX are transparently supported.
.P
Extensions: nfcapd supports a large number of v9 tags. In order to optimise
disk space and performance, v9 tags are grouped into a number of extensions
which may or may not be stored into the data file. Therefore the v9 templates
configured on the exporter may be tuned according the collector. Only those tags 
common to both are stored into the data files.
.P
Sampling: By default, the sampling rate is set to 1 (unsampled) or to any
given value specified by the \-s cmd line option. If sampling information 
is found in the netflow stream, it overwrites the default value. Sampling 
is automatically recognised when announced in v9 option templates 
(tags #34, #35 or #48, #49, #50 ) or in the unofficial v5 header hack. 
Note: Not all platforms (or IOS/JunOS versions) support exporting sampling 
information in netflow data, even if sampling is configured. The number 
of bytes/packets in each netflow record is automatically multiplied by the 
sampling rate.  The total number of flows is not changed as this is not 
accurate enough. (Small flows versus large flows) If the default sampling rate
given by -s is negative, this will hard overwrite any device specific 
announced sampling rates.
.P
NSEL/ASA Support: nfcapd can be compiled with NSEL/ASA support included. See
notes on NSEL/ASA
.P
NEL (NAT Event logging): nfcapd can be compiled with CISCO NEL support included.
See notes on NEL.
.P
.SH OPTIONS
.TP 3
.B -p \fIportnum
Specifies the port number to listen. Default port is 9995
.TP 3
.B -b \fIbindhost
Specifies the hostname/IPv4/IPv6 address to bind for listening. This can be 
an IP address or a hostname, resolving to an IP address attached to an interface.
Defaults to any available IPv4 interface, if not specified.
.TP 3
.B -4
Forces nfcapd to listen on IPv4 addresses only. Can be used together with \-b
if a hostname has an IPv4 and IPv6 address record.
.TP 3
.B -6
Forces nfcapd to listen on IPv6 addresses only. Can be used together with \-b
if a hostname has an IPv4 and IPv6 address record. Depending on the socket
implementation \-6 also accepts IPv4 data.
.TP 3
.B -J \fIMulticastGroup
Join the specified IPv4 or IPv6 multicast group for listening. 
.TP 3
.B -R \fIhost[/port}
Enable packet repeater. Send all incoming packets to another \fIhost\fR and \fIport\fR.
\fIhost\fR is either a valid IPv4/IPv6 address, or a valid symbolic hostname, which resolves to 
a IPv6 or IPv4 address. \fIport\fR may be omitted and defaults to port 9995. Note: Due to IPv4/IPv6
accepted addresses the port separator is '/'. Up to 8 repeaters my be defined.
.TP 3
.B -I \fIIdentString ( capital letter i )
Specifies an ident string, which describes the source e.g. the 
name of the router. This string is put into the stat record to identify
the source. Default is 'none'. This is for compatibility with nfdump 1.5.x
and used to specify a single netflow source. See \fI\-n
.TP 3
.B -l \fIbase_directory ( letter ell )
Specifies the base directory to store the output files. 
If a sub hierarchy is specified with \-S the final directory is concatenated 
to \fIbase_directory/sub_hierarchy\fR. This is for compatibility with nfdump 1.5.x
and used to specify a single netflow source. See \fI\-n
.TP 3
.B -n \fI<Ident,IP,base_directory>
Configures a netflow source named \fIIdent\fR and identified by source IP address \fIIP\fR.
The base directory for the flow files is \fIbase_directory\fR. If a sub hierarchy is specified with \-S 
the final directory is concatenated to \fIbase_directory/sub_hierarchy. Multiple netflow 
sources can be specified. All data is sent to the same port specified by \fI\-p\fR.
Note: You must not mix \-n option with \-I and \-l. Use either syntax.
.TP 3
.B -N \fI<file>
Specifies the \fIfile\fR to read to add multiple netflow sources. The file is expected to contain
one netflow source per line based on the same syntax than the -n option. Comments are not interpreted.
Ident collision are not handled if -N is specified multiple times.
.TP 3
.B -M \fI<dynbase_directory>
Specifies the base directory to store the output files. In contrast to -l -M allows to add 
dynamically new flow sources (exporters), as they appear. All exporters send netflow data 
to the same port and IP.  For each dynamically added source, a new directory is created 
with the name of the IPv4/IPv6 address of the exporter. All '.' and ':" in IP addresses 
are replaced be '-' e.g.  10.11.12.13 is converted to the directory name 10-11-12-13.
Note: Please make sure to restrict at host level the potential range of IP addresses 
which are allowed to connect to nfcapd. Otherwise you risk a potential DoS attack on
nfcapd, as nfcapd has no built in restrictions.
.TP 3
.B -f \fI<pcap_file>
Read netflow packets from a give \fIpcap_file\fR instead of the network. This 
requires nfcapd to be compiled with the pcap option and is intended for debugging only.
.TP 3
.B -s \fI<rate>
Apply default sampling rate \fIrate\fR to all netflow records, unless the sampling rate is 
announced by the exporting device. In that case the announced sampling rate is applied. If 
<rate> is negative, this will hard overwrite any device specific announced sampling rates.
.TP 3
.B -S \fI<num>
Allows to specify an additional directory sub hierarchy to store 
the data files. The default is 0, no sub hierarchy, which means the 
files go directly in the base directory (\-l). The base directory (\-l) is
concatenated with the specified sub hierarchy format to form the final 
data directory.  The following hierarchies are defined:
.PD 0
.RS 4
 0 default     no hierarchy levels
.P
 1 %Y/%m/%d    year/month/day
.P
 2 %Y/%m/%d/%H year/month/day/hour
.P
 3 %Y/%W/%u    year/week_of_year/day_of_week
.P
 4 %Y/%W/%u/%H year/week_of_year/day_of_week/hour
.P
 5 %Y/%j       year/day\-of\-year
.P
 6 %Y/%j/%H    year/day\-of\-year/hour
.P
 7 %Y\-%m\-%d    year\-month\-day
.P
 8 %Y\-%m\-%d/%H year\-month\-day/hour
.RE
.PD
.TP 3
.B -T \fI<extension list>
The argument is considered legacy. By default all matching extension sent by the
exporter are stored. You still may overwrite this, if you want to skip certain extansions.
Regardless of the extension list, the following netflow data is stored per record:
first, last, fwd status, tcp flags, proto, (src)tos, src port, dst port, src 
ipaddr, dst ipaddr, in(packets), in(bytes). In addition nfcapd recognises the 
extensions as described below. Some are valid for v5/v7/v9, but most of them make
only sense for v9. Any specified extensions which do not exist in the input netflow 
records are ignored.
.TP 2
   Extensions:
.PD 0
.RS 4
v5/v7/v9/IPFIX extensions:
.P
 1 input/output interface SNMP numbers.
.P
 2 src/dst AS numbers.
.P
 3 src/dst mask, (dst)TOS, direction.
.P
 4 line Next hop IP addr line
.P
 5 line BGP next hop IP addr line
.P
 6 src/dst vlan id labels
.P
 7 counter output packets
.P
 8 counter output bytes
.P
 9 counter aggregated flows
.P
10 in_src/out_dst MAC address
.P
11 in_dst/out_src MAC address
.P
12 MPLS labels 1\-10
.P
13 Exporting router IPv4/IPv6 address
.P
14 Exporting router ID
.P
15 BGP adjacent prev/next AS
.P
16 time stamp flow received by the collector
.P

.P
NSEL/ASA/NAT extensions
.P
26 NSEL     ASA event, xtended event, ICMP type/code
.P
27 NSEL/NAT xlate ports
.P
28 NSEL/NAT xlate IPv4/IPv6 addr
.P
29 NSEL     ASA ACL ingress/egress acl ID
.P
30 NSEL     ASA username
.P

.P
NEL/NAT extensions
.P
31 NAT event, ingress egress vrfid
.P
32 NAT Block port allocation - block start, end step and size
.P

.P
latency extension
.P
64 nfpcapd/nprobe client/server/application latency"},

.B IMPORTANT: 
By default all extension are selected
Extensions can be added/deleted by specifying a ',' separated 
list of extension ids. Each id may be prepended by an optional 
sign +/\- to add or remove a given id from the extension list. 
Shortcuts: The string 'all' means all extensions. The strings
 'nsel' and 'nel' enable all NSEL or NEL extensions respectively.

.P
Examples: 
.P
\-T all       Enables all possible extensions.
.P
\-T +3,+4     Adds extensions 3 and 4 to the defaults 1 and 2.
.P
\-T all,\-8,\-9 Set all extensions but 8 and 9
.P
\-T \-1,4      Removes default extension 1 and adds extension 4
.P
\-T nsel      Enables all required ASA?NSEL extensions
.P
\-T nel       Enables all required nell extensions
.P

.P
Note: Only those tags in common with the exporting device and enabled 
extensions at the collector side are stored into the data files. A detailed 
list which v9 tags are mapped into which extensions is given in the section 
.B NOTES
.RE
.PD
.TP 3
.B -t \fIinterval
Specifies the time interval in seconds to rotate files. The default value 
is 300s ( 5min ). The smallest interval is 2s.
.TP 3
.B -w
Align file rotation with next n minute ( specified by \-t ) interval. 
Example: If interval is 5 min, sync at 0,5,10... wall clock minutes 
Default: no alignment.
.TP 3
.B -x \fIcmd
Run command \fIcmd\fR at the end of every interval, when a new file
becomes available. The following command expansion is available:
.PD 0
.RS 4
%f	Replaced by the file name e.g nfcapd.200907110845 inluding any
.P
     sub hierarchy. ( 2009/07/11/nfcapd.200907110845 )
.P
%d	Replaced by the directory where the file is located.
.P
%t	Replaced by the time ISO format e.g. 200907110845.
.P
%u	Replaced by the UNIX time format.
.P
%i	Replaced ident string given by \-I
.RE
.PD
.TP 3
.B -X
Collect and embed extended statistics. Currently a port and bpp histogram 
is embedded. Mostly experimental for now
.TP 3
.B -e 
Auto expire files at every cycle. \fImax lifetime\fP and \fImax filesize\fP
are defined using nfexpire(1)
.TP 3
.B -P \fIpidfile
Specify name of pidfile. Default is no pidfile.
.TP 3
.B -D
Daemon mode: fork to background and detach from terminal.
Nfcapd terminates on signal TERM, INT and HUP.
.TP 3
.B -u \fIuserid
Change to the user \fIuserid\fP as soon as possible. Only root is allowed
to use this option.
.TP 3
.B -g \fIgroupid
Change to the group \fIgroupid\fP as soon as possible. Only root is allowed 
use this option.
.TP 3
.B -B \fIbufflen
Specifies the socket input buffer length in bytes. For high volume traffic 
( near GB traffic ) it is recommended to set this value as high as possible 
( typically > 100k ), otherwise you risk to lose packets. The default 
is OS ( and kernel )  dependent.
.TP 3
.B -E
Print netflow records in nfdump raw format to stdout. This option is for 
debugging purpose only, to see how incoming netflow data is processed and stored.
.TP 3
.B -j
Compress flows. Use bz2 compression in output file. Note: not recommended while collecting
.TP 3
.B -y
Compress flows. Use LZ4 compression in output file.
.TP 3
.B -z
Compress flows. Use fast LZO1X\-1 compression in output file.
.TP 3
.B -V
Print nfcapd version and exit.
.TP 3
.B -h
Print help text to stdout with all options and exit.
.SH "RETURN VALUE"
Returns 0 on success, or 255 if initialization failed.
.SH "LOGGING"
nfcapd logs to syslog with SYSLOG_FACILITY LOG_DAEMON
For normal operation level 'warning' should be fine. 
More information is reported at level 'info' and 'debug'.
.P
A small statistic about the collected flows, as well as errors
are reported at the end of every interval to syslog with level 'info'.
.SH "EXAMPLES"
All flows are sent to port 9995 from all exporters and stored into a single file. All known v9 tags are taken.
.RS
\fBnfcapd \-z \-w \-D \-T all \-l /netflow/spool/allflows \-I any \-S 2 \-P /var/run/nfcapd.allflows.pid\fP
.RE
.LP
All flows from 2 different exporters are sent to port 8877 and stored in separate directory trees. All known v9 tags are taken. Input buffer size is set to 128000 bytes
.RS
\fBnfcapd \-z \-w \-D \-T all \-p 8877 \-n upstream,192.168.1.1,/netflow/spool/upstream \-n peer,192.168.2.1,/netflow/spool/peer \-S 2 \-B 128000\fP
.RE
.LP
Only accept from from a single exporter and only extension 3,4 and 5 are accepted. Run a given command when files are rotated and automatically expire flows:
.RS
\fBnfcapd \-w \-D \-T 3,4,5 \-n upstream,192.168.1.1,/netflow/spool/upstream \-p 23456 \-B 128000 \-s 100 \-x '/path/command \-r %d/%f'  \-P /var/run/nfcapd/nfcapd.pid \-e\fP
.RE
.LP
.SH NOTES
Multiple netflow sources:
.P
Netflow data may be sent from different exporters to a single nfcapd process. 
Use the \-n option to separate each netflow source to a different data directory.
For compatibility with nfdump 1.5.x, old style \-l/\-I options are still valid.
In that case all flows from all sources are stored in a single file. For high
volume netflow streams, it is still recommended to have a single nfcapd process
per netflow source.
.P
Nfdump supports a large number of v9 and ipfix elements. For a detailed list
chek the netflow_v9 and ipfix header files.
.PD
32 and 64 bit are supported for all counters. 32it AS numbers are supported.
.P
The format of the data files is netflow version independent.
.P
Socket buffer: Setting the socket buffer size is system dependent. 
When starting up, nfcapd returns the number of bytes the buffer was 
actually set. This is done by reading back the buffer size and may 
differ from what you requested. 
.SH "SEE ALSO"
nfdump(1), nfprofile(1), nfreplay(1)
.SH BUGS
No software without bugs! Please report any bugs back to me.
